home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / asg.com / ATSAYGET.DOC < prev    next >
Encoding:
Text File  |  1989-07-07  |  14.8 KB  |  311 lines
  1. Documentation for Version 5.2 of the ATSAYGET unit:
  2.  
  3. The new AtSayGet procedures are built around a powerful LINE EDITOR with Word-
  4. Star (c) compatibility. These features give the functional equivalence of the
  5. dBase (c) @ Line,Row SAY 'prompt' GET <var> [PICTURE] [RANGE] command. Version
  6. 5.2 has 6 new procedures. The line editing keys have been expanded to hook into
  7. the FULL SCREEN EDITOR available in the included ReadASG unit.
  8.   The AtSayGet unit interface follows:
  9.  
  10. UNIT ATSAYGET;
  11.  
  12. INTERFACE
  13.  
  14. USES
  15.  DOS,
  16.  BlueBag;
  17.  
  18. TYPE
  19.  MaxFL     = 1..20;      {Data field length range for numeric procedures}
  20.  FieldTxt  = STRING[78];
  21.  
  22. CONST
  23.  {ASG exit codes; Inspect ASGExit to see how the procedure exited.}
  24.  Aborted   = -1; {ASG proc would not fit in window. Procedure aborted.}
  25.  Undefined =  0; {you should never get this exit code}
  26.  Tab       =  9; {TAB key was pressed}
  27.  Entered   = 13; {ENTER was pressed or the field filled by the operator}
  28.  ShTab     = 15; {SHIFT TAB keys were pressed}
  29.  Escaped   = 27; {ESC key was pressed}
  30.  Up        = 72; {UP key or ^E was pressed}
  31.  Down      = 80; {DOWN key or ^X was pressed}
  32.  ASGExit   : INTEGER = Undefined;
  33.  SpaceBarOK: BOOLEAN = True; { Space bar (dis)allowed in numeric procedures }
  34.  
  35. VAR        { The following 4 globals are automatically set to appropriate
  36.              values but may be modified in your code. EG: SayAttr:=79 will dis-
  37.              play the prompt as white on red, and GetAttr:=65 will display the
  38.              entry field as blue on red (or underlined on a mono screen)    }
  39.  OrgAttr   { Text attribute before entering (and after exiting) an ASG proc }
  40.  SayAttr,  { Text attribute of prompt }
  41.  GetAttr,  { Text attribute of entry field during editing }
  42.  EndAttr,  { Text attribute of entry field after exiting }
  43.            : BYTE;
  44.  
  45. (* BOOLEAN PROCEDURE *)
  46.  
  47. PROCEDURE
  48. AtSayGetBoolean(AtX   :Xrange  ; {X coordinate}
  49.                 AtY   :Yrange  ; {Y coordinate}
  50.                 Say   :FieldTxt; {text of prompt}
  51.             VAR GetB  :BOOLEAN); {Boolean variable; See comments at end of doc}
  52.  
  53. (* CHARACTOR PROCEDURE - new to Version 5.2 *)
  54.  
  55. PROCEDURE
  56. AtSayGetCharPic(X     :Xrange  ;
  57.                 Y     :Yrange  ;
  58.                 Prompt:FieldTxt; {text of prompt}
  59.             VAR GetC  :CHAR    ; {charactor variable}
  60.                 Pic   :CHAR   ); {(see comments on Pic in AtSayGetStrPic below)}
  61.  
  62. (* STRING PROCEDURES *)
  63.  
  64. PROCEDURE
  65. AtSayGetStrLen(AtX   :Xrange  ; {X coordinate}
  66.                AtY   :Yrange  ; {Y coordinate}
  67.                Say   :FieldTxt; {text of prompt}
  68.            VAR GetStr:FieldTxt; {string variable being entered}
  69.                Len   :BYTE   ); {allowed field length of entry}
  70.  
  71. PROCEDURE
  72. AtSayGetStrPic(AtX   :Xrange   ; {X coordinate}
  73.                AtY   :Yrange   ; {Y coordinate}
  74.                Say   :FieldTxt ; {text of prompt}
  75.            VAR GetStr:FieldTxt ; {string variable being entered}
  76.                Pic   :FieldTxt); {picture template}
  77.  
  78.                      {Special PICture charactors:
  79.                       ! converts letters to uppercase
  80.                       # restricts entry to numbers, spaces, signs
  81.                       9 restricts entry to numbers and signs
  82.                       A restricts entry to alphabetic charactors
  83.                       N restricts entry to letters and numbers
  84.                       X allows any charactor}
  85.  
  86.  
  87. (* NUMERIC PROCEDURES *)
  88.  
  89. PROCEDURE
  90. AtSayGetReal(AtX   :Xrange  ; {X coordinate}
  91.              AtY   :Yrange  ; {Y coordinate}
  92.              Say   :FieldTxt; {text of prompt}
  93.          VAR GetR  :REAL    ; {Real numeric variable being entered}
  94.              FldLen:MaxFL   ; {Length of entry field}
  95.              DecPl :INTEGER); {decimal places}
  96.  
  97. PROCEDURE
  98. AtSayGetLongInt(AtX   :Xrange  ; {X coordinate}
  99.                 AtY   :Yrange  ; {Y coordinate}
  100.                 Say   :FieldTxt; {text of prompt}
  101.             VAR GetLI :LONGINT ; {LongInt numeric variable being entered}
  102.                 FldLen:MaxFL  ); {Length of entry field (FldLen>10 is useless)}
  103.  
  104. PROCEDURE
  105. AtSayGetInt(AtX   :Xrange  ; {X coordinate}
  106.             AtY   :Yrange  ; {Y coordinate}
  107.             Say   :FieldTxt; {text of prompt}
  108.         VAR GetInt:INTEGER ; {Integer numeric variable being entered}
  109.             FldLen:MaxFL  ); {Length of entry field. (FldLen>6 is useless)}
  110.  
  111. PROCEDURE
  112. AtSayGetWord(AtX   :Xrange  ; {X coordinate}
  113.              AtY   :Yrange  ; {Y coordinate}
  114.              Say   :FieldTxt; {text of prompt}
  115.          VAR GetW  :WORD    ; {Word numeric variable being entered}
  116.              FldLen:MaxFL  ); {Length of entry field. (FldLen>5 is useless)}
  117.  
  118.  
  119.  
  120.     The all new AtSayGetRange procedures shell around the AtSayGet numeric
  121. procedures (which are but shells around the AtSayGetStrPic string procedure).
  122. Using the AtSayGetRange procedures let you to specify a minimum and maximum
  123. allowable range of input. There are 4 Range procedures which all follow the
  124. syntax of their corresponding ASG numeric procedures except that they require
  125. two additional parameters: the first is the Minimum allowed range and the 2nd
  126. is the Maximum allowed range.
  127.  
  128. PROCEDURE
  129. AtSayGetRealRange(AtX   :Xrange  ; {X coordinate}
  130.                   AtY   :Yrange  ; {Y coordinate}
  131.                   Say   :FieldTxt; {text of prompt}
  132.               VAR GetR  :REAL    ; {numeric variable being entered}
  133.                   FldLen,          {allowed field length of entry}
  134.                   DecPl :MacFL   ; {decimal places}
  135.                   Min,             {minimum acceptable value}
  136.                   Max   :REAL   ); {maximum acceptable value}
  137.  
  138. PROCEDURE
  139. AtSayGetLongIntRange(AtX   :Xrange  ; {X coordinate}
  140.                      AtY   :Yrange  ; {Y coordinate}
  141.                      Say   :FieldTxt; {text of prompt}
  142.                  VAR GetLI :LONGINT ; {numeric variable being entered}
  143.                      FldLen:MaxFL   ; {allowed field length of entry}
  144.                      Min,             {minimum acceptable value}
  145.                      Max   :LONGINT); {maximum acceptable value}
  146.  
  147. PROCEDURE
  148. AtSayGetIntRange(X     :Xrange  ; {X coordinate}
  149.                  Y     :Yrange  ; {Y coordinate}
  150.                  Prompt:FieldTxt; {text of prompt}
  151.              VAR GetI  :INTEGER ; {numeric variable being entered}
  152.                  FldLen:MaxFL   ; {allowed field length of entry}
  153.                  Min,             {minimum acceptable value}
  154.                  Max   :INTEGER); {minimum acceptable value}
  155.  
  156. PROCEDURE
  157. AtSayGetWordRange(X     :Xrange  ; {X coordinate}
  158.                   Y     :Yrange  ; {Y coordinate}
  159.                   Prompt:FieldTxt; {text of prompt}
  160.               VAR GetW  :WORD    ; {numeric variable being entered}
  161.                   FldLen:MaxFL   ; {allowed field length of entry}
  162.                   Min,             {minimum acceptable value}
  163.                   Max   :WORD   ); {minimum acceptable value}
  164.  
  165.   Finally, the simple AtSay procedure used by all of the above has been in-
  166. terfaced. If you are using the procedures in this unit you might as well use
  167. AtSay rather than GoToXY(x,y); WRITE('Something to say');
  168.  
  169. PROCEDURE AtSay(X     :Xrange   ;
  170.                 Y     :Yrange   ;
  171.                 Prompt:FieldTxt); {Prompt is displayed according to SayAttr}
  172.  
  173. EDITING KEYS
  174.  
  175. When you are positioned in a data field certain keys and combinations
  176. of keys will facilitate editing. If the operator is familiar with dBase or
  177. WordStar (s)he will find that the editing keys noted below are very similar.
  178.  
  179. Key(s)         Function                                           ASGExit
  180. -------------- -------------------------------------------------- -------
  181. <-,   ^S . . . Move cursor one character to the left.                 0
  182. ->,   ^D . . . Move cursor one character to the right.                0
  183. ^ <-, ^A . . . Move cursor one word to the left.                      0
  184. ^ ->, ^F . . . Move cursor one word to the right.                     0
  185. Home, ^Z . . . Move to the start of the field.                        0
  186. End,  ^B . . . Move to the last character in the field.               0
  187. Del,  ^G . . . Delete the character at the cursor position and
  188.                pull over all the characters on the right.             0
  189. ^T . . . . . . Delete word to right and pull over remaining text.     0
  190. ^Y . . . . . . Delete the whole field.                                0
  191. ^R . . . . . . Restore field to its original state before edit.       0
  192. BackSpace  . . Delete the character to the left of the cursor and
  193.                pull over all the characters on the right.             0
  194. Ins,  ^V . . . Toggles insert on/off. Block cursor for insert mode.   0
  195. SpaceBar . . . Move cursor to the right. If insert is off it will
  196.                over-write any characters, otherwise it will push them
  197.                to the right as it moves.                              0
  198. Tab  . . . . . Accepts the field and exits if the entry is valid.     9
  199. Enter  . . . .    "     "    "    "    "    "  "    "    "   "        13
  200. Shift Tab  . .    "     "    "    "    "    "  "    "    "   "        15
  201. Esc  . . . . . Exits procedure abandoning any edits that were made    27
  202. UP,   ^E . . . Accepts the field and exits if the entry is valid.     72
  203. DOWN, ^X . . .    "     "    "    "    "    "  "    "    "   "        80
  204.  
  205.                SPECIAL CONSIDERATIONS:
  206.  
  207. Compiler Settings:
  208.      Programs using the AtSayGet or ASGRange units must be compiled with the
  209. Options/Compiler/Var-string checking as RELAXED, or include the {$V-} compiler
  210. directive.
  211.  
  212. Initialization of variables:
  213.      All formal variable parameters passed to one of the AtSayGet pro-
  214. cedures should first be properly initialized as the current value of the
  215. variable will be displayed in the data field. For example, if you are using
  216. the AtSayGetStrLen procedure to enter a new STRING[10] variable without first
  217. properly initializing the variable with an actual or nul value, 10 "random"
  218. charactors will be displayed in the entry field until a ^Y is issued or the
  219. field is filled with data by the operator.
  220.      Special care must taken with variables passed to the AtSayGetStrPic
  221. procedure to initialize the formal variable with the exact length of spaces
  222. or text equal to SizeOf(GetStr).
  223.      When using an AtSayGet procedure to enter numeric data you will also wish
  224. to initialize the variable. All numerals in the entry field, even if they are
  225. seperated with spaces, will compose the value passed by the procedure. Thus,
  226. in a field the length of 4 the entry [12_0] will be returned as [ 120]. This
  227. is different than the way dBase accepts numeric input (which, in this example,
  228. would return [  12] ).
  229.  
  230. Screen considerations:
  231.      Unlike some other line editors the prompts in these AtSayGet procedures
  232. are positioned on the screen in the normal Pascal X,Y (column,row) format. The
  233. dBase style Y,X (row,column) positioning is fine for dBase programmers but we
  234. use Pascal and should maintain consistency in conventions.
  235.      All of the AtSayGet procedures work equally well on either a mono or color
  236. display. With a color display the procedures automatically adapt to the back-
  237. ground color and display the prompt and field in an appropriate color. The de-
  238. fault colors c/b altered by changing the global variables SayAttr & GetAttr.
  239.      The AtSayGet string procedures indicate insert mode with a block cursor
  240. and overwrite mode with a normal cursor. Upon exit the cursor is set to the
  241. default state for the type of monitor being used. Thus, if you have entered an
  242. AtSayGet procedure with a modified cursor and you want it the same after exit-
  243. ing, you will have to re-modify the cursor in your subsequent code.
  244.      Note that the maximum X-coordinate is 79 and the maximum Y-coordinate is
  245. 25. Nevertheless, these procedures will not wrap on the screen, but rather will
  246. just exit without doing anything if (X+Length(Prompt)+[field length]) > 80.
  247. Likewise, when an AtSayGet procedure is used in a window that is narrower than
  248. 80 the procedure will exit without running if it would otherwise wrap in the
  249. window. In either case ASGExit is set to Aborted (-1).
  250.  
  251. Range checking:
  252.      Numeric range checking routines are incorporated within the AtSayGet
  253. numeric procedures. Thus, if the operator enters a negative number in a
  254. AtSayGetWord field the bell will ring and the message ERROR will be briefly
  255. displayed.
  256.      The RANGE clause of dBase was emulated by writing a shell around the
  257. AtSayGet numeric procedures. With an AtSayGetRange procedure an entry that is
  258. too small will sound the bell, briefly fill the field with <<<<<<<..., and re-
  259. set the field to the minimum allowed range. If the entry is too large the bell
  260. sounds, the field is briefly filled with >>>>>>>..., and the field reset to the
  261. maximum allowed value. The procedure will not exit until a valid range is
  262. entered. If you program an illogical range (EG: 70000,-5 in AtSayGetWordRange)
  263. a compiler range error or run-time range error will be generated.
  264.  
  265. Valid AtSayGetBoolean enteries:
  266. Affirmative entries are: '+','t','T','y','Y'
  267. Negative entries are:    '-','f','F','n','N'
  268.  
  269. Demonstration of procedures:
  270.      Compile and run DEMO.PAS to see how the procedures in this unit can
  271. be used. When looking at the code notice how the variables are initialized.
  272.  
  273. *  *  *  *  *  *  *  *  * *  *  *  *  *  *  *  *  * *  *  *  *  *  *  *
  274.  
  275.  
  276.  
  277.          ----------------end-of-author's-documentation---------------
  278.  
  279.                         Software Library Information:
  280.  
  281.                    This disk copy provided as a service of
  282.  
  283.                         The Public (Software) Library
  284.  
  285.          We are not the authors of this program, nor are we associated
  286.          with the author in any way other than as a distributor of the
  287.          program in accordance with the author's terms of distribution.
  288.  
  289.          Please direct shareware payments and specific questions about
  290.          this program to the author of the program, whose name appears
  291.          elsewhere in  this documentation. If you have trouble getting
  292.          in touch with the author,  we will do whatever we can to help
  293.          you with your questions. All programs have been tested and do
  294.          run.  To report problems,  please use the form that is in the
  295.          file PROBLEM.DOC on many of our disks or in other written for-
  296.          mat with screen printouts, if possible.  The P(s)L cannot de-
  297.          bug programs over the telephone.
  298.  
  299.          Disks in the P(s)L are updated monthly, so if you did not get
  300.          this disk  directly from the P(s)L,  you should be aware that
  301.          the files in this set may no  longer be the current versions.
  302.  
  303.          For a copy of the latest monthly software library newsletter
  304.          and a list of the 1,800+ disks in the library, call or write
  305.  
  306.                         The Public (Software) Library
  307.                               P.O.Box 35705 - F
  308.                            Houston, TX 77235-5705
  309.                                (713) 665-7017
  310.  
  311.